FORMAT: 1A
HOST: http://localhost:8080

# Flutter News Example API (v1.0.0)

Flutter News Example API is an API which allows consumers to interact with sample news content.

# Root [/]

## Status Check [GET]

This action allows consumers to verify the status of the server. A response status code `204` indicates that the server is healthy.

+ Response 204 (application/json)

## Articles [/api/v1/articles]

Resources related to news articles.

### Get Article [GET /api/v1/articles/{id}{?limit,offset}]

This action allows you to query article content for a specific article.

+ Parameters
    + id (required, string) - The article identifier.
    + limit (optional, number) - The number of content blocks to return.
        + Default: 20
    + offset (optional, number) - The (zero-based) offset of the first item in the collection to return.
        + Default: 0

+ Response 200 (application/json)
    + Attributes (object)
        + content (required, array[Block]) - The list of blocks that composes the article content.
        + total_count (optional, number) - The total number of available blocks.
        + url (required, string) - The url for the associated article.

    + Body
        
            {
                "content": [
                    {
                        "title": "Breaking News",
                        "type": "__section_header__"
                    },                    
                ],
                "total_count": 42,
                "url": "https://dailyglobe.com"
            }

### Get Related Articles [GET /api/v1/articles/{id}/related{?limit,offset}]

This action allows you to query article content related to a specific article.

+ Parameters
    + id (required, string) - The article identifier.
    + limit (optional, number) - The number of content blocks to return.
        + Default: 20
    + offset (optional, number) - The (zero-based) offset of the first item in the collection to return.
        + Default: 0

+ Response 200 (application/json)
    + Attributes (object)
        + related_articles (required, array[Block]) - The list of blocks that composes the related articles list.
        + total_count (optional, number) - The total number of available blocks.

    + Body
        
            {
                "related_articles": [
                    {
                        "id": "b1fc2ffc-eb02-42ce-af65-79702172a987",
                        "category": "health",
                        "author": "Northwestern University",
                        "published_at": "2022-03-11T00:00:00.000",
                        "image_url": "https://scitechdaily.com/images/Ear-Hearing-Concept.jpg",
                        "title": "Restoring Hearing: New Tool To Create Ear Hair Cells Lost Due to Aging or Noise - SciTechDaily",
                        "description": "‘We have overcome a major hurdle’ to restore hearing, investigators say. Gene discovery allows the production of inner or outer ear hair cells, death of outer hair cells due to aging or noise cause most hearing loss...",
                        "is_premium": false,
                        "type": "__post_small__"
                    }
                ],
                "total_count": 1,
            }


## Categories [/api/v1/categories]

Resources related to news categories.

### Get Categories [GET]

This action allows you to query all available news categories.

+ Response 200 (application/json)
    + Attributes (object)
        + categories (required, array[Category]) - The list of available news categories.

    + Body
        
            {
                "categories": [
                    "technology",
                    "sports",
                    "top"
                ]                
            }

## Feed [/api/v1/feed{?category,limit,offset}]

Resources related to the news feed.

+ Parameters
    + category (optional, Category) - The headline category.
        + Default: general
        + Members            
            + business
            + entertainment
            + general
            + health
            + science
            + sports
            + technology
    + limit (optional, number) - The number of results to return.
        + Default: 20
    + offset (optional, number) - The (zero-based) offset of the first item in the collection to return.
        + Default: 0

### Get Feed [GET]

This action allows you to query feeds.

+ Response 200 (application/json)
    + Attributes (object)
        + feed (required, array[Block]) - The list of blocks that composes the feed.
        + total_count (optional, number) - The total number of available blocks.

    + Body
        
            {
                "feed": [
                    {
                        "title": "Breaking News",
                        "type": "__section_header__"
                    },
                    {
                        "type": "__divider_horizontal__"
                    },
                    {
                        "id": "499305f6-5096-4051-afda-824dcfc7df23",
                        "category": "technology",
                        "author": "Sean Hollister",
                        "published_at": "2022-03-09T00:00:00.000",
                        "image_url": "https://cdn.vox-cdn.com/thumbor/OTpmptgr7XcTVAJ27UBvIxl0vrg=/0x146:2040x1214/fit-in/1200x630/cdn.vox-cdn.com/uploads/chorus_asset/file/22049166/shollister_201117_4303_0003.0.jpg",
                        "title": "Nvidia and AMD GPUs are returning to shelves and prices are finally falling",
                        "is_premium": false,
                        "type": "__post_large__",
                        "action": {
                            "article_id": "499305f6-5096-4051-afda-824dcfc7df23",
                            "type": "__navigate_to_article__"
                        }
                    },
                    {
                        "type": "__spacer__",
                        "spacing": "medium"
                    },
                    {
                        "id": "82c49bf1-946d-4920-a801-302291f367b5",
                        "category": "sports",
                        "author": "Tom Dierberger",
                        "published_at": "2022-03-10T00:00:00.000",
                        "image_url":"https://www.nbcsports.com/sites/rsnunited/files/styles/metatags_opengraph/public/article/hero/pat-bev-ja-morant-USA.jpg",
                        "title": "Patrick Beverley throws shade at Warriors for Ja Morant struggles - NBC Sports",
                        "description": "Patrick Beverley is no longer participating in the NBA playoffs, but he sure has a lot to say. In Game 2 between the Warriors and Memphis Grizzlies on Tuesday night, Ja Morant torched the Dubs for 47 points...",
                        "is_premium": false,
                        "type": "__post_medium__",
                        "action": {
                            "article_id": "82c49bf1-946d-4920-a801-302291f367b5",
                            "type": "__navigate_to_article__"
                        }
                    },
                    {
                        "spacing": "small",
                        "type": "__spacer__"
                    },
                    {
                        "id": "b1fc2ffc-eb02-42ce-af65-79702172a987",
                        "category": "health",
                        "author": "Northwestern University",
                        "published_at": "2022-03-11T00:00:00.000",
                        "image_url": "https://scitechdaily.com/images/Ear-Hearing-Concept.jpg",
                        "title": "Restoring Hearing: New Tool To Create Ear Hair Cells Lost Due to Aging or Noise - SciTechDaily",
                        "description": "‘We have overcome a major hurdle’ to restore hearing, investigators say. Gene discovery allows the production of inner or outer ear hair cells, death of outer hair cells due to aging or noise cause most hearing loss...",
                        "is_premium": false,
                        "type": "__post_small__",
                        "action": {
                            "article_id": "b1fc2ffc-eb02-42ce-af65-79702172a987",
                            "type": "__navigate_to_article__"
                        }
                    },
                    {
                        "spacing": "extraSmall",
                        "type": "__spacer__"
                    },
                    {
                        "category": "science",
                        "tiles": [
                            {
                                "id": "384a15ff-a50e-46d5-96a7-8864facdcc48",
                                "category": "science",
                                "author": "Loren Grush",
                                "published_at": "2022-05-06T00:00:00.000",
                                "image_url": "https://cdn.vox-cdn.com/thumbor/eqkJgsUMn-iJOrN98c4gduFGDT8=/0x74:1050x624/fit-in/1200x630/cdn.vox-cdn.com/uploads/chorus_asset/file/23441881/Screen_Shot_2022_05_06_at_1.13.12_AM.png",
                                "title": "SpaceX successfully returns four astronauts from the International Space Station - The Verge",
                                "is_premium": false,
                                "type": "__post_grid_tile__",
                                "action": {
                                    "article_id": "384a15ff-a50e-46d5-96a7-8864facdcc48",
                                    "type": "__navigate_to_article__"
                                }
                            },
                            {
                                "id": "13e448bb-cd26-4ae0-b138-4a67067f7a93",
                                "category": "science",
                                "author": "Daniel Strain",
                                "published_at": "2022-05-06T00:00:00.000",
                                "image_url": "https://scx2.b-cdn.net/gfx/news/2022/a-surging-glow-in-a-di.jpg",
                                "title": "A surging glow in a distant galaxy could change the way we look at black holes",
                                "is_premium": false,
                                "type": "__post_grid_tile__",
                                "action": {
                                    "article_id": "13e448bb-cd26-4ae0-b138-4a67067f7a93",
                                    "type": "__navigate_to_article__"
                                }
                            }
                        ],
                        "type": "__post_grid_group__"
                    },
                    }
                ],
                "total_count": 100,
            }

## Newsletter [/api/v1/newsletter]

Resources related to newsletters.

### Subscribe to Newsletter [POST /api/v1/newsletter/subscription]

This action allows you to subscribe a user to a newsletter.

+ Request
    + Body
            
            {
                "email": "<EMAIL_ADDRESS>"
            }

+ Response 201 (application/json)

## Search [/api/v1/search]

Resources related to search.

### Popular Search [GET /api/v1/search/popular]

This action allows you to search for popular news content.

+ Response 200 (application/json)
    + Attributes (object)
        + topics (required, array[string]) - The list of popular topics.
        + articles (required, array[Block]) - The list of popular article blocks.

    + Body
        
            {
                "topics": ["Aging", "Health", "Genetics"],
                "articles": [
                    {
                        "id": "b1fc2ffc-eb02-42ce-af65-79702172a987",
                        "category": "health",
                        "author": "Northwestern University",
                        "published_at": "2022-03-11T00:00:00.000",
                        "image_url": "https://scitechdaily.com/images/Ear-Hearing-Concept.jpg",
                        "title": "Restoring Hearing: New Tool To Create Ear Hair Cells Lost Due to Aging or Noise - SciTechDaily",
                        "description": "‘We have overcome a major hurdle’ to restore hearing, investigators say. Gene discovery allows the production of inner or outer ear hair cells, death of outer hair cells due to aging or noise cause most hearing loss...",
                        "is_premium": false,
                        "type": "__post_small__"
                    }
                ],
            }

### Relevant Search [GET /api/v1/search/relevant{?q}]

This action allows you to search for relevant news content.

+ Parameters
    + q (required, string) - The query string.    

+ Response 200 (application/json)
    + Attributes (object)
        + topics (required, array[string]) - The list of relevant topics.
        + articles (required, array[Block]) - The list of relevant article blocks.

    + Body
        
            {
                "topics": ["Aging", "Health", "Genetics"],
                "articles": [
                    {
                        "id": "b1fc2ffc-eb02-42ce-af65-79702172a987",
                        "category": "health",
                        "author": "Northwestern University",
                        "published_at": "2022-03-11T00:00:00.000",
                        "image_url": "https://scitechdaily.com/images/Ear-Hearing-Concept.jpg",
                        "title": "Restoring Hearing: New Tool To Create Ear Hair Cells Lost Due to Aging or Noise - SciTechDaily",
                        "description": "‘We have overcome a major hurdle’ to restore hearing, investigators say. Gene discovery allows the production of inner or outer ear hair cells, death of outer hair cells due to aging or noise cause most hearing loss...",
                        "is_premium": false,
                        "type": "__post_small__"
                    }
                ],
            }

## Subscriptions [/api/v1/subscriptions]

Resources related to subscriptions.

### Create a Subscription [POST]

This action allows you to create a subscription for the associated user.

+ Response 201 (application/json)

### Get Subscriptions [GET]

This action allows you to query all available subscriptions.

+ Response 200 (application/json)
    + Attributes (object)
        + subscriptions (required, array[Subscription]) - The list of subscriptions.

    + Body
        
            {
                "subscriptions": [
                    {
                        "id": "17e79fca-853a-40e3-b4a7-291a64d3846b",
                        "name": "premium",
                        "cost": {
                            "monthly": 1499,
                            "annual":16200
                        },
                        "benefits": [
                            "No ads",
                            "Access to premium content",
                            "Unlimited reads"
                        ]
                    }
                ],
            }

## Users [/api/v1/users]

Resources related to users.

### Get Current User [GET /api/v1/users/me]

This action allows you query information about the current user.

+ Response 200 (application/json)
    + Attributes (object)
        + user (required, User) - The currently authenticated user.

    + Body
        
            {
                "user": {
                  "id": "2e99887d-d672-4b96-ad6a-123c1c7fa3fa",
                  "subscription_plan": "premium",
                }
            }

# Data Structures

## Block (object)

+ type (required, BlockType) - the block type.

## BlockType (enum)

+ "__section_header__" - a section header block
+ "__divider_horizontal__" - a divider horizontal block
+ "__spacer__" - a spacer block
+ "__post_large__" - a post large block
+ "__post_medium__" - a post medium block
+ "__post_small__" - a post small block
+ "__post_grid_group__" - a post grid group block
+ "__post_grid_tile__" - a post grid tile block
+ "__text_caption__" - a text caption block
+ "__text_headline__" - a text headline block
+ "__text_lead_paragraph__" - a text lead paragraph block
+ "__text_paragraph__" - a text paragraph block
+ "__image__" - an image block
+ "__video__" - a video block
+ "__unknown__" - an unrecognized block
+ "__trending_story__ - a trending story block

## Category (enum)

+ business - news relating to business
+ entertainment - news relating to entertainment
+ top - breaking news 
+ health - news relating to health
+ science - news relating to science
+ sports - news relating to sports
+ technology - news relating to technology

## Subscription (object)

+ id (required, string) - the unique subscription identifier
+ name (required, string) - the human readable subscription name
+ cost (required, SubscriptionCost) - the cost for the subscription
+ benefits (required, array[string]) - list of benefits associated with the subscription


## SubscriptionCost (object)

+ monthly (required, number) - the monthly cost of the subscription in cents
+ annual (required, number) - the annual cost of the subscription in cents

## SubscriptionPlan (enum)

+ none - no subscription plan
+ basic - a basic subscription plan
+ plus - a plus subscription plan
+ premium - a premium subscription plan

## User (object)

+ id (required, string) - the unique user identifier (username)
+ subscription_plan (required, SubscriptionPlan) - the user's current subscription plan.